MCP Selenium WebDriver

# Servidor MCP Selenium WebDriver Un servidor MCP (Model Context Protocol) completo que implementa Selenium WebDriver para automatización de navegadores con capacidades avanzadas de evasión de detección, soporte para múltiples navegadores y funcionalidades completas de interacción web. ## Características Principales ### 🚀 Automatización Completa de Navegadores - **Navegación web**: Navegar a URLs, obtener información de páginas - **Interacción con elementos**: Buscar, hacer clic, escribir texto, subir archivos - **Acciones de ratón**: Hover, drag and drop, clic derecho, doble clic - **Manejo de teclado**: Envío de teclas especiales (Enter, Tab, flechas, etc.) - **Capturas de pantalla**: Pantalla completa o elementos específicos - **Ejecución de JavaScript**: Scripts personalizados en el navegador ### 🕵️ Evasión de Detección Avanzada - **Undetected Chrome**: Integración con undetected-chromedriver - **Randomización**: User agents y viewports aleatorios - **Scripts stealth**: Ocultación de propiedades de automatización - **Simulación humana**: Escritura y scroll con delays realistas - **Gestión de cookies**: Control completo de cookies y sesiones ### 🌐 Soporte Multi-Navegador - **Chrome**: Soporte completo con evasión de detección - **Firefox**: Implementación nativa de Selenium - **Detección automática**: Identificación de navegadores instalados - **Configuraciones específicas**: Optimizaciones por navegador ### ⚙️ Gestión Avanzada de Sesiones - **Múltiples sesiones**: Hasta 10 sesiones simultáneas por defecto - **Gestión automática**: Limpieza de sesiones expiradas - **Configuraciones flexibles**: Presets para diferentes casos de uso - **Proxies**: Soporte para HTTP, HTTPS y SOCKS ## Instalación ### Requisitos Previos - Python 3.8 o superior - Chrome y/o Firefox instalados - Dependencias del sistema para Selenium ### Instalación de Dependencias ```bash # Clonar o descargar el proyecto cd mcp_selenium_server # Instalar dependencias de Python pip install -r requirements.txt ``` ### Dependencias del Sistema #### Ubuntu/Debian ```bash # Chrome wget -q -O - https://dl.google.com/linux/linux_signing_key.pub | sudo apt-key add - echo "deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main" | sudo tee /etc/apt/sources.list.d/google-chrome.list sudo apt update sudo apt install google-chrome-stable # Firefox sudo apt install firefox ``` #### CentOS/RHEL ```bash # Chrome sudo yum install -y google-chrome-stable # Firefox sudo yum install firefox ``` #### Windows - Descargar e instalar Chrome desde https://www.google.com/chrome/ - Descargar e instalar Firefox desde https://www.mozilla.org/firefox/ #### macOS ```bash # Con Homebrew brew install --cask google-chrome brew install --cask firefox ``` ## Configuración ### Configuraciones Predefinidas El servidor incluye tres configuraciones predefinidas: #### 1. Configuración por Defecto ```python DEFAULT_CONFIG = ServerConfig( max_sessions=10, session_timeout=3600, default_browser="chrome", browser_options=BrowserOptions( headless=False, window_width=1920, window_height=1080, incognito=True ) ) ``` #### 2. Configuración Stealth (Recomendada para evasión) ```python STEALTH_CONFIG = ServerConfig( browser_options=BrowserOptions( headless=True, user_agent="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36...", disable_images=True, custom_args=[ "--disable-blink-features=AutomationControlled", "--disable-dev-shm-usage", "--no-first-run", # ... más argumentos stealth ] ), detection_evasion=DetectionEvasionConfig( use_undetected_chrome=True, stealth_mode=True, randomize_user_agent=True, randomize_viewport=True ) ) ``` #### 3. Configuración de Rendimiento ```python PERFORMANCE_CONFIG = ServerConfig( browser_options=BrowserOptions( headless=True, disable_images=True, disable_javascript=False, custom_args=[ "--disable-dev-shm-usage", "--disable-gpu", "--no-sandbox" ] ) ) ``` ### Configuración de Proxies ```python proxy_config = { "http": "http://proxy.example.com:8080", "https": "https://proxy.example.com:8080", "socks": "socks5://proxy.example.com:1080" } ``` ## Uso Básico ### Iniciar el Servidor ```bash # Modo desarrollo python server.py # Con MCP CLI mcp dev server.py # Instalar en Claude Desktop mcp install server.py ``` ### Ejemplo de Uso Básico ```python # 1. Iniciar navegador result = start_browser( browser_type="chrome", options={ "headless": False, "window_width": 1920, "window_height": 1080 }, detection_evasion={ "use_undetected_chrome": True, "stealth_mode": True } ) session_id = result["session_id"] # 2. Navegar a una página navigate_to_url(session_id, "https://example.com") # 3. Buscar un elemento element = find_element( session_id=session_id, strategy="css_selector", value="input[name='search']" ) # 4. Escribir texto type_text( session_id=session_id, strategy="css_selector", value="input[name='search']", text="selenium automation" ) # 5. Hacer clic en botón click_element( session_id=session_id, strategy="css_selector", value="button[type='submit']" ) # 6. Tomar captura de pantalla take_screenshot( session_id=session_id, file_path="/path/to/screenshot.png" ) # 7. Cerrar navegador close_browser(session_id) ``` ## Herramientas MCP Disponibles ### Gestión de Navegadores | Herramienta | Descripción | |-------------|-------------| | `start_browser` | Inicia una nueva sesión de navegador | | `close_browser` | Cierra una sesión específica | | `detect_available_browsers` | Detecta navegadores instalados | | `get_recommended_browser` | Obtiene el navegador recomendado | | `check_browser_support` | Verifica soporte de WebDriver | ### Navegación y Páginas | Herramienta | Descripción | |-------------|-------------| | `navigate_to_url` | Navega a una URL específica | | `get_page_info` | Obtiene información de la página actual | | `execute_script` | Ejecuta JavaScript en el navegador | ### Interacción con Elementos | Herramienta | Descripción | |-------------|-------------| | `find_element` | Busca elementos con diferentes estrategias | | `click_element` | Hace clic en un elemento | | `type_text` | Escribe texto en un elemento | | `upload_file` | Sube archivos a inputs de tipo file | ### Acciones Avanzadas | Herramienta | Descripción | |-------------|-------------| | `perform_mouse_action` | Acciones de ratón (hover, drag & drop) | | `send_keys` | Envía teclas especiales | | `take_screenshot` | Captura pantalla completa o elementos | ### Evasión de Detección | Herramienta | Descripción | |-------------|-------------| | `apply_stealth_mode` | Aplica todas las técnicas stealth | | `randomize_user_agent` | Cambia a un user agent aleatorio | | `randomize_viewport` | Cambia el tamaño de ventana | | `simulate_human_typing` | Escritura con delays humanos | | `scroll_like_human` | Scroll gradual simulando humano | | `add_random_delay` | Agrega delays aleatorios | ### Gestión de Sesiones | Herramienta | Descripción | |-------------|-------------| | `list_active_sessions` | Lista todas las sesiones activas | | `get_session_info` | Información detallada de una sesión | | `close_all_sessions` | Cierra todas las sesiones | | `cleanup_expired_sessions` | Limpia sesiones expiradas | ### Gestión de Cookies | Herramienta | Descripción | |-------------|-------------| | `manage_cookies` | Gestión completa de cookies | ### Configuración del Servidor | Herramienta | Descripción | |-------------|-------------| | `get_server_status` | Estado actual del servidor | | `update_server_config` | Actualiza configuración con presets | ## Ejemplos Avanzados ### Automatización con Evasión de Detección ```python # Configuración stealth completa session_result = start_browser( browser_type="chrome", options={ "headless": True, "disable_images": True, "incognito": True }, detection_evasion={ "use_undetected_chrome": True, "stealth_mode": True, "randomize_user_agent": True, "randomize_viewport": True } ) session_id = session_result["session_id"] # Aplicar modo stealth adicional apply_stealth_mode(session_id) # Navegar con delays humanos navigate_to_url(session_id, "https://example.com") add_random_delay(1.0, 3.0) # Scroll humano scroll_like_human(session_id, "down", 500, 8) add_random_delay(0.5, 1.5) # Escritura humana simulate_human_typing( session_id=session_id, strategy="id", value="search-input", text="automated search query", min_delay=0.05, max_delay=0.15 ) # Gestión de cookies manage_cookies( session_id=session_id, action="add", cookie_data={ "name": "session_token", "value": "abc123", "domain": "example.com" } ) ``` ### Automatización de Formularios ```python # Llenar formulario complejo session_id = start_browser("chrome")["session_id"] navigate_to_url(session_id, "https://forms.example.com") # Campos de texto type_text(session_id, "id", "first_name", "John") type_text(session_id, "id", "last_name", "Doe") type_text(session_id, "id", "email", "john.doe@example.com") # Seleccionar dropdown click_element(session_id, "id", "country_select") click_element(session_id, "xpath", "//option[text()='United States']") # Subir archivo upload_file( session_id=session_id, strategy="id", value="file_upload", file_path="/path/to/document.pdf" ) # Checkbox click_element(session_id, "id", "terms_checkbox") # Enviar formulario click_element(session_id, "css_selector", "button[type='submit']") # Esperar y verificar add_random_delay(2.0, 4.0) page_info = get_page_info(session_id) print(f"Página actual: {page_info['title']}") ``` ### Scraping con Múltiples Sesiones ```python # Iniciar múltiples sesiones sessions = [] urls = ["https://site1.com", "https://site2.com", "https://site3.com"] for i, url in enumerate(urls): result = start_browser( browser_type="chrome", options={"headless": True}, detection_evasion={"use_undetected_chrome": True} ) session_id = result["session_id"] sessions.append(session_id) # Navegar en paralelo navigate_to_url(session_id, url) apply_stealth_mode(session_id) # Procesar cada sesión for i, session_id in enumerate(sessions): # Extraer datos elements = find_element( session_id=session_id, strategy="css_selector", value=".data-item", multiple=True ) # Tomar captura take_screenshot( session_id=session_id, file_path=f"/screenshots/site_{i+1}.png" ) # Limpiar todas las sesiones close_all_sessions() ``` ## Estrategias de Localización de Elementos El servidor soporta todas las estrategias estándar de Selenium: | Estrategia | Descripción | Ejemplo | |------------|-------------|---------| | `id` | Por atributo ID | `"search-button"` | | `name` | Por atributo name | `"username"` | | `class_name` | Por clase CSS | `"btn-primary"` | | `tag_name` | Por nombre de etiqueta | `"button"` | | `css_selector` | Selector CSS | `"div.container > p"` | | `xpath` | Expresión XPath | `"//div[@class='content']//p"` | | `link_text` | Texto exacto del enlace | `"Click here"` | | `partial_link_text` | Texto parcial del enlace | `"Click"` | ### Ejemplos de Selectores ```python # Por ID find_element(session_id, "id", "submit-btn") # Por clase CSS find_element(session_id, "class_name", "form-control") # Selector CSS complejo find_element(session_id, "css_selector", "div.modal .btn-primary:not(:disabled)") # XPath avanzado find_element(session_id, "xpath", "//table//tr[contains(@class, 'data-row')][position()>1]") # Múltiples elementos find_element(session_id, "css_selector", ".product-item", multiple=True) ``` ## Configuración de Proxies ### Tipos de Proxy Soportados ```python # HTTP Proxy proxy_config = {"http": "http://proxy.example.com:8080"} # HTTPS Proxy proxy_config = {"https": "https://proxy.example.com:8080"} # SOCKS Proxy proxy_config = {"socks": "socks5://proxy.example.com:1080"} # Proxy con autenticación proxy_config = {"http": "http://user:pass@proxy.example.com:8080"} # Usar proxy al iniciar navegador start_browser( browser_type="chrome", proxy=proxy_config, options={"headless": True} ) ``` ## Manejo de Errores El servidor maneja automáticamente los errores comunes y proporciona mensajes descriptivos: ```python # Ejemplo de respuesta con error { "success": False, "error": "Timeout: Elemento no encontrado", "message": "No se pudo encontrar elemento con id='missing-element' en 10 segundos" } # Ejemplo de respuesta exitosa { "success": True, "session_id": "abc123-def456", "message": "Navegador chrome iniciado exitosamente" } ``` ### Errores Comunes y Soluciones | Error | Causa | Solución | |-------|-------|----------| | `Sesión no encontrada` | ID de sesión inválido | Verificar que la sesión esté activa | | `Timeout: Elemento no encontrado` | Selector incorrecto o elemento no visible | Revisar selector y aumentar timeout | | `WebDriverException` | Problema con el driver | Reinstalar webdriver-manager | | `ElementNotInteractableException` | Elemento no clickeable | Usar scroll o esperar a que sea visible | ## Mejores Prácticas ### Para Evasión de Detección 1. **Usar configuración stealth**: Siempre aplicar `STEALTH_CONFIG` para sitios que detectan bots 2. **Delays aleatorios**: Agregar delays entre acciones para simular comportamiento humano 3. **Randomización**: Cambiar user agents y viewports regularmente 4. **Gestión de cookies**: Mantener cookies de sesión para parecer un usuario real 5. **Scroll gradual**: Usar `scroll_like_human` en lugar de scroll instantáneo ### Para Rendimiento 1. **Modo headless**: Usar para operaciones en lote 2. **Deshabilitar imágenes**: Reducir tiempo de carga 3. **Gestión de sesiones**: Cerrar sesiones no utilizadas 4. **Timeouts apropiados**: Configurar timeouts según la velocidad del sitio ### Para Estabilidad 1. **Manejo de errores**: Siempre verificar `success` en las respuestas 2. **Limpieza de sesiones**: Usar `cleanup_expired_sessions` regularmente 3. **Verificar elementos**: Usar `find_element` antes de interactuar 4. **Capturas de pantalla**: Tomar capturas para debugging ## Limitaciones - **Máximo de sesiones**: 10 sesiones simultáneas por defecto (configurable) - **Timeout de sesión**: 1 hora por defecto (configurable) - **Navegadores soportados**: Chrome y Firefox únicamente - **Detección**: Algunos sitios avanzados pueden detectar automatización ## Solución de Problemas ### Problemas de Instalación ```bash # Error: ChromeDriver no encontrado pip install --upgrade webdriver-manager # Error: Dependencias del sistema sudo apt-get install -y libgconf-2-4 libxss1 libxtst6 libxrandr2 libasound2 libpangocairo-1.0-0 libatk1.0-0 libcairo-gobject2 libgtk-3-0 libgdk-pixbuf2.0-0 # Error: Permisos sudo chmod +x /usr/bin/google-chrome ``` ### Problemas de Ejecución ```bash # Verificar navegadores disponibles python -c " from browser_detection import BrowserDetection bd = BrowserDetection() print(bd.detect_available_browsers()) " # Probar configuración básica python -c " from webdriver_manager import WebDriverManager wm = WebDriverManager() driver = wm.create_driver('chrome', BrowserOptions()) print('Chrome funciona correctamente') driver.quit() " ``` ## Contribución Para contribuir al proyecto: 1. Fork el repositorio 2. Crear una rama para la nueva característica 3. Implementar cambios con tests 4. Enviar pull request ## Licencia Este proyecto está bajo la licencia MIT. Ver archivo LICENSE para más detalles. ## Soporte Para reportar bugs o solicitar características: - Crear un issue en el repositorio - Incluir logs de error y configuración utilizada - Especificar sistema operativo y versión de navegador --- **Desarrollado por Manus AI** - Automatización de navegadores inteligente y confiable.